home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / clu / readme.man < prev    next >
Lisp/Scheme  |  1993-08-14  |  7KB  |  156 lines
  1.  
  2.     ***     CLU  online manual (in Emacs) --  version 1.1    ***
  3.     ------------------------------------------------------------
  4.     ( Created by  Boaz Ben-Zvi  <boaz@lcs.mit.edu>  Jan. 31, 1991)
  5.  
  6.   This directory contains the files needed to put the CLU manual online as 
  7. part of the Emacs help facility.
  8.   (Basically the Emacs help facility is extended with operations to support 
  9. Clu help in a manner similar to Emacs' help).
  10.   The file  clu-manual.tar.Z  contains the following files:
  11.  
  12.  - CLU-DOC : Contains the CLU manual in a format similar to Emacs' DOC file.
  13.  - CLU-DOC-keys.el : Contains keys and indexes for the CLU-DOC file (can be
  14.     generated from a CLU-DOC file by calling clu-doc-snarf-file).
  15.  - clu-doc.el : The collection of Emacs-lisp functions that do the work.
  16.  - README : This file.
  17.  
  18. --------------------------------------------------------------------------
  19.  
  20. TO INSTALL:
  21.  
  22.   Put the files CLU-DOC and CLU-DOC-keys.el in some directory (e.g., 
  23. /usr/lib/clu/manual/). You can set the variable  clu-doc-file-name  (in your 
  24. .emacs or in this file) to the full path name of your CLU-DOC file (e.g.,
  25. (setq clu-doc-file-name "/usr/lib/clu/manual/CLU-DOC") ), else you will be 
  26. prompted for that name (can also be set by calling  M-x clu-doc-visit-file)
  27.   If you ever want to modify the CLU-DOC file for some reason, you'll have
  28. to regenerate the CLU-DOC-keys.el file by calling  M-x clu-doc-snarf-file .
  29.  
  30. --------------------------------------------------------------------------
  31.  
  32. TO LOAD:
  33.  
  34.   Load the file  clu-doc.el[c]  into your Emacs. For example, put in 
  35. your .emacs file something like:
  36.  
  37.   (load "/mit/6.170/manual/clu-doc" 'no-error)
  38.  
  39. You can also load it while inside Emacs:
  40.  
  41.   M-x load-file  <RETURN>
  42.   Load file: /mit/6.170/manual/clu-doc.elc
  43.  
  44. ---------------------------------------------------------------------------
  45.  
  46. TO USE:
  47.  
  48. Once loaded, just call help ( normaly by hitting Control-h ) followed by
  49. one of the keys:
  50.  
  51. 1. 'd' -- for help on Clu symbols (types or operations. Examples: int$mul, 
  52.       array, ARRAY$FILL, FILE_NAME, stream$primary_output, string$s2ac)
  53. 2. 'g' -- for general Clu documentation topics (Examples: TERMINAL_I/O, FILE,
  54.       own_variables, CLUSTERS, syntactic_sugar).
  55. 3. '/' -- for Clu apropos (give partial name, like FILE, and get a list of all
  56.       the Clu symbols and topics that include that name).
  57.  
  58. EXAMPLE:
  59.   You type           C-h d
  60.   Emacs prompts with     Describe CLU symbol: 
  61.   You type         oneof$make_  <RETURN>
  62.   Emacs splits your screen and gives help about the operation ONEOF$MAKE_
  63.  
  64. Note that:
  65. - case is unimportant. 
  66. - The help text is taken from the Clu manual (Appendix A in the 6.170 book).
  67. - Symbol completion works (hit the TAB key); for example, if you type  ARRAY$
  68.   followed by TAB, you'll get a list of possible completions (all the 
  69.   operations of ARRAY in this case).
  70. - If the cursor is placed on a Clu symbol when you call C-h d, emacs would 
  71.   propose that symbol as default; for example, if your cursor is placed 
  72.   someplace on "ARRAY[foo]$FILL" in your file, and you type C-h d , emacs 
  73.   would prompt:   "Describe CLU symbol (default ARRAY$FILL): ", typing RETURN
  74.   would select this default.
  75.  
  76. ---------------------------------------------------------------------------
  77.  
  78. HELP ON USE:  ( a short version of this file )
  79.  
  80.  After loading, type  M-x (i.e. META x) clu-doc-help
  81.  
  82. ---------------------------------------------------------------------------
  83.  
  84. ADDING USER DEFINED  ABSTRACTIONS TO THE MANUAL:
  85.  
  86.   You can add you CLU files to the current session of the CLU on-line manual
  87. by calling  M-x (i.e. META x) clu-doc-add-file and giving it a name of one
  88. of your clu files.
  89.   Using  clu-doc-add-directory  instead takes a directory and adds all the
  90. CLU files in that directory to the current session of the CLU manual. Emacs
  91. "knows" which files are CLU files by matching the files' suffixes with the
  92. content of the Emacs variable  clu-doc-file-suffix (normally ".clu").  You
  93. can change this variable (M-x set-variable) if you want (e.g., when adding
  94. ".spc" files).
  95.   Once added, you can not change the specification you added, but they will
  96. disappear once you exit Emacs.
  97.  
  98. DUMPING AND LOADING:
  99.  
  100.    You can also dump the specifications of your CLU files into dump files
  101. and then load these dump files (same effect as adding these CLU files to the
  102. current session of the CLU on-line manual).
  103.    Use  M-x clu-doc-dump-file  to dump a CLU file into a dump file. This
  104. operation actually appends to the dump file, so you can dump CLU files
  105. again and again to the same dump file. (This call also asks you about adding
  106. the dumped spec to the current session of the CLU manual).
  107.    Use  M-x clu-doc-load-file  to load a dump file.
  108.    To make life easy: when Emacs initializes a new session of the CLU manual,
  109. it loads all the dump files listed in the list  clu-doc-dumped-files-to-load .
  110. Thus by setting this variable to the list of your dump files, you do not
  111. have to load them by hand.
  112.  
  113. EXAMPLE:
  114.  
  115. I make my dump files
  116.  
  117.   M-x clu-doc-dump-file  <RETURN>
  118.   Give name of a CLU file: /mit/boaz/project/graph.clu  <RETURN>
  119.   File to append this dump to: /mit/boaz/project/PROJECT-DUMP  <RETURN>
  120.   Also add to current CLU manual? (y or n)   <n>
  121.   M-x clu-doc-dump-file  <RETURN>
  122.   Give name of a CLU file: /mit/boaz/project/table.clu  <RETURN>
  123.   File to append this dump to: /mit/boaz/project/PROJECT-DUMP  <RETURN>
  124.   Also add to current CLU manual? (y or n)   <n>
  125.   ...............................
  126.   ................................
  127.   M-x clu-doc-dump-file   <RETURN>
  128.   Give name of a CLU file: /mit/boaz/6.170/part1.clu  <RETURN>
  129.   File to append this dump to: /mit/boaz/project/PS-DUMP  <RETURN>
  130.   Also add to current CLU manual? (y or n)   <n>
  131.   ................................
  132.  
  133. in my .emacs:
  134.   (setq clu-doc-load-file '("~/project/PROJECT-DUMP" "~/6.170/PS-DUMP"))
  135.  
  136. and after starting, I hit  C-h d  and can get to my types (clusters),
  137. procedures, iterators etc., as well as the CLU built in definitions.
  138.  
  139. TOTAL DUMPING:
  140.  
  141.   You can create a new version of CLU-DOC that includes some of your user
  142. defined abstractions by:
  143. -- Starting the CLU on-line manual.
  144. -- Adding your definitions ( M-x clu-doc-add-file, clu-doc-add-directory )
  145. -- dump the whole current session using  M-x clu-doc-total-dump . This
  146.    would create a new CLU-DOC style file and the appropriate -keys.el file.
  147.  
  148. You can set your  clu-doc-file-name variable (in .emacs) so that the new
  149. version would be used. Thus you'll have your definitions as part of the manual.
  150.  
  151. ---------------------------------------------------------------------------
  152.  
  153. Please send comments, complaints, bug reports etc. to Boaz Ben-Zvi at
  154.  boaz@athena.mit.edu (or boaz@lcs.mit.edu)
  155.  
  156.